TL;DR: Adds full support for control-flow constructs in code_builder:

• if / else if / else (+ if-case) (resolves Add ability to generate if-else blocks #834)
• while, do-while (resolves Add support for while #939)
• for, for-in, await for
• try / catch / finally
• switch statements and expressions
• collection control-flow: if, else, for, for-in (resolves LiteralMapExpression needs support for collection-if expression #1145, resolves Add support for control flow expressions #890)

Background

The implementation is loosely based around discussions in #834. Several ideas were proposed in that thread, but it appears none have been implemented. The primary issue with control-flow implementation, as summed up by @matanlurey, is that:

The problem with builders for statements is there are so many, and it is hard to cover everything.

This implementation works around that issue by using shared visitor logic, similar to the "compound statement builder" idea proposed by @eredo, taking advantage of the fact that all control-flow blocks in Dart are essentially formatted the same. Loosely, every control block can be broken down into:

expression {
  body
}

Going off of that, we really only have to implement visitors for three logical "levels" of control blocks, those being:

• ControlExpression, a control-flow expression
• ControlBlock, a ControlExpression followed by a bracketed body
• ControlTree, a "tree" of multiple ControlBlocks (ie if/else if/else)

For (almost) every concrete implementation of a control-flow block, all it takes is then implementing ControlBlock or ControlTree and the visiting logic comes free of charge.

Control Expressions

Control Expressions are implemented via the internal-only ControlExpression class, a new Expression subtype. The visitor logic for this class is the most complex due to the amount of variation in the formatting of control-flow expressions. It provides numerous constructors, covering each type of control-flow expression (if, for, while, etc.), and should (hopefully) be extendable enough to easily accommodate new control expression types if/when the language is updated.

The class is internal-only, as all of its functionality is exposed via friendlier public builders. Making it public would only add scope noise and potential confusion.

Similar to the way ExpressionVisitor and ExpressionEmitter are structured, this adds ControlBlockVisitor and ControlBlockEmitter as abstract mixin classes mixed into DartEmitter. Visitor logic for ControlExpression is in these control block mixins (rather than the expression ones) for maintainability, as it is easier to have everything in one place instead of arguably the most important part being in a separate file.

Control Blocks

Control Blocks are implemented via the internal-only ControlBlock mixin class. Rather than just exporting that, I decided on something similar to what @TekExplorer proposed, where each specific type of control block implements a public "helper" builder on top of ControlBlock to make the API more user-friendly. In total, there are 5 of these builders:

• ForLoop (for)
• ForInLoop (for-in, await for)
• WhileLoop* (while, do-while)
• Condition (if, else if, else) (single) (see conversation)
  • Supports if-case via ConditionBuilder.ifCase BranchBuilder.ifCase
• CatchBlock (catch)

WhileLoop requires a custom visitor due to the existence of the do-while loop, which does not follow the "standard" control block format. All others simply mix in ControlBlock.

I opted not to support single-line control blocks (with no brackets). These are entirely stylistic; functionally it does not matter whether if (value) return; has brackets or not, and if (value) return; is really the only place where this would be used, as it is bad form to omit the braces if the statement body overflows onto the next line. That being said, I did add Expression.ifThenReturn which is shorthand to generate such an expression and which, out of simplicity, omits the braces (see Expression Helpers).

You may have noticed that I didn't include switch statements in this section. No surprise, they also required a separate visitor, among other unique implementation details, so they are in their own section, see Switches.

Control Trees

Control Trees are implemented via the internal-only ControlTree mixin class, using the same helper builder concept as control blocks. In total there are two such builders:

• IfTree Conditional for creating if-else trees (see conversation)
• TryCatch for try/catch/finally trees.

IfTree was named that way instead of something like ConditionalTree in order to avoid autocomplete conflicts with Condition when using the API, which proved to be sufficiently annoying during development. (see conversation)

As try and finally blocks don't have any parameters, TryCatch implements them as a Block for simplicity, hence the lack of a TryBlock or FinallyBlock. CatchBlock is not implemented this way to support customizing the error/stacktrace parameter names as well as on clauses.

Switches

The implementation for switch statements and expressions is fairly complex, largely due to the existence of two different switch types. Because of this, most functionality is located in the internal-only Switch and SwitchBuilder classes, which both switch subtypes (SwitchStatement and SwitchExpression) then extend.

Rather than confusingly exposing two Case types (switch is bad enough), generic Case<T> is public, with the switch-specific implementations being in two separate internal classes, CaseStatement and CaseExpression. Case<T> is not visitable; the aforementioned specific implementations each implement Code and have their own visitors.

The two switch types each provide a private getter _cases, which converts the Case<T>s from the switch's public cases field into their visitable, switch-specific counterparts. When visited, the switch's ControlExpression is generated, and _cases is used to create a Block. These two values are then passed into a BuildableSwitch, yet another internal-only class, which implements ControlBlock.

After all that (admittedly convoluted) conversion, the BuildableSwitch is passed into the control block visitor and from then on generated the same way as any other ControlBlock.

Expression Helpers

Several helper methods were also added to Expression to facilitate easier usage of control-flow blocks. Rather than adding them to Expression directly, they were added to ControlFlow, an extension on Expression. This was done primarily for ease of maintenance due to the unwieldy nature of expression.dart, but also to allow users of the package to easily be able opt-out of these specific helpers via hide if desired.

Added the following helpers:

• Expression.yielded, Expression.yieldStarred
• Expression.ifThen
  • Expression.ifThenReturn
• Expression.loopWhile, Expression.loopDoWhile
• Expression.loopForIn

Additionally added some static helpers to ControlFlow:

• ControlFlow.breakVoid, ControlFlow.breakLabel
• ControlFlow.continueVoid, ControlFlow.continueLabel
• ControlFlow.returnVoid
• ControlFlow.rethrowVoid
• ControlFlow.ifCase

Finally, static Expression.wildcard was also added. It was added to Expression rather than ControlFlow as it felt more idiomatic (a wildcard isn't really a control flow statement like the others on ControlFlow are)

Collection Control-Flow

Collection control-flow support was implemented as static methods on the ControlFlow extension, particularly:

• ControlFlow.collectionIf
• ControlFlow.collectionElse
• ControlFlow.collectionFor
• ControlFlow.collectionForIn

These are fairly simple; however, they did require some slight changes to visitAll and the various collection literal visitors in order to support chaining, ie:

[if (value) item else other] // ✅ works
[if (value) item, else other] // ❌ doesn't work

{ if (value) key: item else otherKey: other } // ✅ works
{ if (value) key: item, else otherKey: other } // ❌ doesn't work

I tried to implement this via a child/nesting system, but that ended up becoming prohibitively complicated (primarily due to map literals). A chaining-based system proved to be much simpler.

Other Changes

• The current .g.dart files were generated with an older version of built_value and contained some redundant checks and new keyword usage. When I ran the built script it updated all those files, so I've also pushed those versions.
• Fixed some typos in the expression_test.dart file and on the changelog (also, apologies, I guess my editor automatically formatted the changelog and replaced all - with *, something which I didn't realize until just now as I am writing this)
• Rewrote part of the README to be more beginner friendly (I'll take this out if it isn't allowed (I haven't contributed here before so I'm not sure), it was just a personal gripe I had from when I used this the first time)
• Bumped the version from 4.10.2-wip to 4.11.0-wip in pubspec.yaml
• Added relevant changelog entries

Tests

Added comprehensive unit tests for all changes. Per package:coverage and LCOV, all touched files (excluding generated .g.dart) have at least 97% test coverage.

Happy to answer any questions or make any changes requested, I've got lots of free time at the moment and this is something I'd love to see code_builder support.

• [✅] I’ve reviewed the contributor guide and applied the relevant portions to this PR.